home *** CD-ROM | disk | FTP | other *** search
-
-
-
- menu(n) Tk Commands
-
-
-
- _________________________________________________________________
-
- NAME
- menu - Create and manipulate menu widgets
-
- SYNOPSIS
- menu _p_a_t_h_N_a_m_e ?_o_p_t_i_o_n_s?
-
- STANDARD OPTIONS
- activeBackground background disabledForeground|
- activeBorderWidth borderWidth font |
- activeForeground cursor foreground |
-
- See the ``options'' manual entry for details on the standard
- options.
-
- WIDGET-SPECIFIC OPTIONS
- Name: postCommand
- Class: Command |
- Command-Line Switch:-postcommand |
-
- ||
- If this option is specified then it provides a Tcl com- |
- mand to execute each time the menu is posted. The com- |
- mand is invoked by the post widget command before post- |
- ing the menu.
-
- Name: selector
- Class: Foreground
- Command-Line Switch:-selector
-
- For menu entries that are check buttons or radio but-
- tons, this option specifies the color to display in the
- selector when the check button or radio button is
- selected.
- _________________________________________________________________
-
-
- INTRODUCTION
- The menu command creates a new top-level window (given by
- the _p_a_t_h_N_a_m_e argument) and makes it into a menu widget.
- Additional options, described above, may be specified on the
- command line or in the option database to configure aspects
- of the menu such as its colors and font. The menu command
- returns its _p_a_t_h_N_a_m_e argument. At the time this command is
- invoked, there must not exist a window named _p_a_t_h_N_a_m_e, but
- _p_a_t_h_N_a_m_e's parent must exist.
-
- A menu is a widget that displays a collection of one-line
- entries arranged in a column. There exist several different
- types of entries, each with different properties. Entries
- of different types may be combined in a single menu. Menu
-
-
-
- Tk 1
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- entries are not the same as entry widgets. In fact, menu
- entries are not even distinct widgets; the entire menu is
- one widget.
-
- Menu entries are displayed with up to three separate fields.
- The main field is a label in the form of text or a bitmap,
- which is determined by the -label or -bitmap option for the
- entry. If the -accelerator option is specified for an
- entry then a second textual field is displayed to the right
- of the label. The accelerator typically describes a keys-
- troke sequence that may be typed in the application to cause
- the same result as invoking the menu entry. The third field
- is a _s_e_l_e_c_t_o_r. The selector is present only for check-
- button or radio-button entries. It indicates whether the
- entry is selected or not, and is displayed to the left of
- the entry's string.
-
- In normal use, an entry becomes active (displays itself dif-
- ferently) whenever the mouse pointer is over the entry. If
- a mouse button is released over the entry then the entry is
- _i_n_v_o_k_e_d. The effect of invocation is different for each
- type of entry; these effects are described below in the sec-
- tions on individual entries.
-
- Entries may be _d_i_s_a_b_l_e_d, which causes their labels and
- accelerators to be displayed with dimmer colors. A disabled
- entry cannot be activated or invoked. Disabled entries may
- be re-enabled, at which point it becomes possible to
- activate and invoke them again.
-
-
- COMMAND ENTRIES
- The most common kind of menu entry is a command entry, which
- behaves much like a button widget. When a command entry is
- invoked, a Tcl command is executed. The Tcl command is
- specified with the -command option.
-
-
- SEPARATOR ENTRIES
- A separator is an entry that is displayed as a horizontal
- dividing line. A separator may not be activated or invoked,
- and it has no behavior other than its display appearance.
-
-
- CHECK-BUTTON ENTRIES
- A check-button menu entry behaves much like a check-button
- widget. When it is invoked it toggles back and forth
- between the selected and deselected states. When the entry
- is selected, a particular value is stored in a particular
- global variable (as determined by the -onvalue and -variable
- options for the entry); when the entry is deselected
- another value (determined by the -offvalue option) is stored
-
-
-
- Tk 2
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- in the global variable. A selector box is displayed to the
- left of the label in a check-button entry. If the entry is
- selected then the box's center is displayed in the color
- given by the selector option for the menu; otherwise the
- box's center is displayed in the background color for the
- menu. If a -command option is specified for a check-button
- entry, then its value is evaluated as a Tcl command each
- time the entry is invoked; this happens after toggling the
- entry's selected state.
-
-
- RADIO-BUTTON ENTRIES
- A radio-button menu entry behaves much like a radio-button
- widget. Radio-button entries are organized in groups of
- which only one entry may be selected at a time. Whenever a
- particular entry becomes selected it stores a particular
- value into a particular global variable (as determined by
- the -value and -variable options for the entry). This
- action causes any previously-selected entry in the same
- group to deselect itself. Once an entry has become
- selected, any change to the entry's associated variable will
- cause the entry to deselect itself. Grouping of radio-
- button entries is determined by their associated variables:
- if two entries have the same associated variable then they
- are in the same group. A selector diamond is displayed to
- the left of the label in each radio-button entry. If the
- entry is selected then the diamond's center is displayed in
- the color given by the selector option for the menu; other-
- wise the diamond's center is displayed in the background
- color for the menu. If a -command option is specified for a
- radio-button entry, then its value is evaluated as a Tcl
- command each time the entry is invoked; this happens after
- selecting the entry.
-
-
- CASCADE ENTRIES
- A cascade entry is one with an associated menu (determined
- by the -menu option). Cascade entries allow the construc-
- tion of cascading menus. When the entry is activated, the
- associated menu is posted just to the right of the entry;
- that menu remains posted until the higher-level menu is
- unposted or until some other entry is activated in the
- higher-level menu. The associated menu should normally be a
- child of the menu containing the cascade entry, in order for
- menu traversal to work correctly.
-
- A cascade entry posts its associated menu by invoking a Tcl
- command of the form
-
- _m_e_n_u post _x _y
-
-
-
-
-
- Tk 3
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- where _m_e_n_u is the path name of the associated menu, _x and _y
- are the root-window coordinates of the upper-right corner of
- the cascade entry, and _g_r_o_u_p is the name of the menu's group
- (as determined in its last post widget command). The
- lower-level menu is unposted by executing a Tcl command with
- the form
-
- _m_e_n_u unpost
-
- where _m_e_n_u is the name of the associated menu.
-
- If a -command option is specified for a cascade entry then
- it is evaluated as a Tcl command each time the associated |
- menu is posted (the evaluation occurs before the menu is |
- posted).
-
-
- WIDGET COMMAND
- The menu command creates a new Tcl command whose name is
- _p_a_t_h_N_a_m_e. This command may be used to invoke various opera-
- tions on the widget. It has the following general form:
-
- _p_a_t_h_N_a_m_e _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
-
- _O_p_t_i_o_n and the _a_r_gs determine the exact behavior of the com-
- mand.
-
- Many of the widget commands for a menu take as one argument
- an indicator of which entry of the menu to operate on.
- These indicators are called _i_n_d_e_xes and may be specified in
- any of the following forms:
-
- _n_u_m_b_e_r Specifies the entry numerically, where 0
- corresponds to the top-most entry of the menu, 1
- to the entry below it, and so on.
-
- active Indicates the entry that is currently active.
- If no entry is active then this form is
- equivalent to none. This form may not be abbre-
- viated.
-
- last Indicates the bottommost entry in the menu. If
- there are no entries in the menu then this form
- is equivalent to none. This form may not be
- abbreviated.
-
- none Indicates ``no entry at all''; this is used
- most commonly with the activate option to deac-
- tivate all the entries in the menu. In most
- cases the specification of none causes nothing
- to happen in the widget command. This form may
- not be abbreviated.
-
-
-
- Tk 4
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- @_n_u_m_b_e_r In this form, _n_u_m_b_e_r is treated as a y-
- coordinate in the menu's window; the entry
- spanning that y-coordinate is used. For exam-
- ple, ``@0'' indicates the top-most entry in the
- window. If _n_u_m_b_e_r is outside the range of the
- window then this form is equivalent to none.
-
- _p_a_t_t_e_r_n If the index doesn't satisfy one of the above
- forms then this form is used. _P_a_t_t_e_r_n is
- pattern-matched against the label of each entry
- in the menu, in order from the top down, until a
- matching entry is found. The rules of
- Tcl_StringMatch are used.
-
- The following widget commands are possible for menu widgets:
-
- _p_a_t_h_N_a_m_e activate _i_n_d_e_x
- Change the state of the entry indicated by _i_n_d_e_x to
- active and redisplay it using its active colors. Any
- previously-active entry is deactivated. If _i_n_d_e_x is
- specified as none, or if the specified entry is dis-
- abled, then the menu ends up with no active entry.
- Returns an empty string.
-
- _p_a_t_h_N_a_m_e add _t_y_p_e ?_o_p_t_i_o_n _v_a_l_u_e _o_p_t_i_o_n _v_a_l_u_e ...?
- Add a new entry to the bottom of the menu. The new
- entry's type is given by _t_y_p_e and must be one of cas-
- cade, checkbutton, command, radiobutton, or separator,
- or a unique abbreviation of one of the above. If addi-
- tional arguments are present, they specify any of the
- following options:
-
- -activebackground _v_a_l_u_e
- Specifies a background color to use for displaying |
- this entry when it is active. If this option is |
- specified as an empty string (the default), then |
- the activeBackground option for the overall menu |
- is used. This option is not available for separa- |
- tor entries.
-
- -accelerator _v_a_l_u_e
- Specifies a string to display at the right side of
- the menu entry. Normally describes an accelerator
- keystroke sequence that may be typed to invoke the
- same function as the menu entry. This option is
- not available for separator entries.
-
- -background _v_a_l_u_e
- Specifies a background color to use for displaying |
- this entry when it is in the normal state (neither |
- active nor disabled). If this option is specified |
- as an empty string (the default), then the |
-
-
-
- Tk 5
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- background option for the overall menu is used. |
- This option is not available for separator |
- entries.
-
- -bitmap _v_a_l_u_e
- Specifies a bitmap to display in the menu instead
- of a textual label, in any of the forms accepted
- by Tk_GetBitmap. This option overrides the -label
- option but may be reset to an empty string to
- enable a textual label to be displayed. This
- option is not available for separator entries.
-
- -command _v_a_l_u_e
- For command, checkbutton, and radiobutton entries,
- specifies a Tcl command to execute when the menu |
- entry is invoked. For cascade entries, specifies |
- a Tcl command to execute when the entry is |
- activated (i.e. just before its submenu is |
- posted). Not available for separator entries.
-
- -font _v_a_l_u_e
- Specifies the font to use when drawing the label |
- or accelerator string in this entry. If this |
- option is specified as an empty string (the |
- default) then the font option for the overall menu |
- is used. This option is not available for separa- |
- tor entries.
-
- -label _v_a_l_u_e
- Specifies a string to display as an identifying
- label in the menu entry. Not available for
- separator entries.
-
- -menu _v_a_l_u_e
- Available only for cascade entries. Specifies the
- path name of the menu associated with this entry.
-
- -offvalue _v_a_l_u_e
- Available only for check-button entries. Speci-
- fies the value to store in the entry's associated
- variable when the entry is deselected.
-
- -onvalue _v_a_l_u_e
- Available only for check-button entries. Speci-
- fies the value to store in the entry's associated
- variable when the entry is selected.
-
- -state _v_a_l_u_e
- Specifies one of three states for the entry: nor- |
- mal, active, or disabled. In normal state the |
- entry is displayed using the foreground option for |
- the menu and the background option from the entry |
-
-
-
- Tk 6
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- or the menu. The active state is typically used |
- when the pointer is over the entry. In active |
- state the entry is displayed using the activeFore- |
- ground option for the menu along with the |
- activebackground option from the entry. Disabled |
- state means that the entry is insensitive: it |
- doesn't activate and doesn't respond to mouse but- |
- ton presses or releases. In this state the entry |
- is displayed according to the disabledForeground |
- option for the menu and the background option from |
- the entry. This option is not available for |
- separator entries. |
-
- -underline _v_a_l_u_e ||
- Specifies the integer index of a character to |
- underline in the entry. This option is typically |
- used to indicate keyboard traversal characters. 0 |
- corresponds to the first character of the text |
- displayed in the entry, 1 to the next character, |
- and so on. If a bitmap is displayed in the entry |
- then this option is ignored. This option is not |
- available for separator entries.
-
- -value _v_a_l_u_e
- Available only for radio-button entries. Speci-
- fies the value to store in the entry's associated
- variable when the entry is selected.
-
- -variable _v_a_l_u_e
- Available only for check-button and radio-button
- entries. Specifies the name of a global value to
- set when the entry is selected. For check-button
- entries the variable is also set when the entry is
- deselected. For radio-button entries, changing
- the variable causes the currently-selected entry
- to deselect itself.
-
- The add widget command returns an empty string.
-
- _p_a_t_h_N_a_m_e configure ?_o_p_t_i_o_n? ?_v_a_l_u_e _o_p_t_i_o_n _v_a_l_u_e ...?
- Query or modify the configuration options of the
- widget. If no _o_p_t_i_o_n is specified, returns a list
- describing all of the available options for _p_a_t_h_N_a_m_e
- (see Tk_ConfigureInfo for information on the format of
- this list). If _o_p_t_i_o_n is specified with no _v_a_l_u_e, then
- the command returns a list describing the one named
- option (this list will be identical to the correspond-
- ing sublist of the value returned if no _o_p_t_i_o_n is
- specified). If one or more _o_p_t_i_o_n-_v_a_l_u_e pairs are
- specified, then the command modifies the given widget
- option(s) to have the given value(s); in this case the
- command returns an empty string. _O_p_t_i_o_n may have any
-
-
-
- Tk 7
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- of the values accepted by the menu command.
-
- _p_a_t_h_N_a_m_e delete _i_n_d_e_x_1 ?_i_n_d_e_x_2?
- Delete all of the menu entries between _i_n_d_e_x_1 and |
- _i_n_d_e_x_2 inclusive. If _i_n_d_e_x_2 is omitted then it |
- defaults to _i_n_d_e_x_1. Returns an empty string.
-
- _p_a_t_h_N_a_m_e disable _i_n_d_e_x
- Change the state of the entry given by _i_n_d_e_x to dis- |
- abled and redisplay the entry using its disabled |
- colors. Returns an empty string. This command is |
- obsolete and will eventually be removed; use ``_p_a_t_h_N_a_m_e |
- entryconfigure _i_n_d_e_x -state disabled'' instead.
-
- _p_a_t_h_N_a_m_e enable _i_n_d_e_x
- Change the state of the entry given by _i_n_d_e_x to normal |
- and redisplay the entry using its normal colors. |
- Returns an empty string. This command is obsolete and |
- will eventually be removed; use ``_p_a_t_h_N_a_m_e entryconfig- |
- ure _i_n_d_e_x -state normal'' instead.
-
- _p_a_t_h_N_a_m_e entryconfigure _i_n_d_e_x ?_o_p_t_i_o_n_s?
- This command is similar to the configure command,
- except that it applies to the options for an individual
- entry, whereas configure applies to the options for the
- menu as a whole. _O_p_t_i_o_n_s may have any of the values
- accepted by the add widget command. If _o_p_t_i_o_n_s are
- specified, options are modified as indicated in the
- command and the command returns an empty string. If no
- _o_p_t_i_o_n_s are specified, returns a list describing the
- current options for entry _i_n_d_e_x (see Tk_ConfigureInfo
- for information on the format of this list).
-
- _p_a_t_h_N_a_m_e index _i_n_d_e_x
- Returns the numerical index corresponding to _i_n_d_e_x, or
- none if _i_n_d_e_x was specified as none.
-
- _p_a_t_h_N_a_m_e invoke _i_n_d_e_x
- Invoke the action of the menu entry. See the sections
- on the individual entries above for details on what
- happens. If the menu entry is disabled then nothing
- happens. If the entry has a command associated with it
- then the result of that command is returned as the
- result of the invoke widget command. Otherwise the
- result is an empty string. Note: invoking a menu
- entry does not automatically unpost the menu. Normally
- the associated menubutton will take care of unposting
- the menu.
-
- _p_a_t_h_N_a_m_e post _x _y
- Arrange for the menu to be displayed on the screen at
- the root-window coordinates given by _x and _y. These
-
-
-
- Tk 8
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- coordinates are adjusted if necessary to guarantee that
- the entire menu is visible on the screen. This command
- normally returns an empty string. If the -postcommand |
- option has been specified, then its value is executed |
- as a Tcl script before posting the menu and the result |
- of that script is returned as the result of the post |
- widget command. If an error returns while executing |
- the command, then the error is returned without posting |
- the menu.
-
- _p_a_t_h_N_a_m_e unpost
- Unmap the window so that it is no longer displayed. If
- a lower-level cascaded menu is posted, unpost that
- menu. Returns an empty string.
-
- _p_a_t_h_N_a_m_e yposition _i_n_d_e_x
- Returns a decimal string giving the y-coordinate within
- the menu window of the topmost pixel in the entry
- specified by _i_n_d_e_x.
-
-
-
- DEFAULT BINDINGS
- Tk automatically creates class bindings for menus that give |
- them the following default behavior: |
-
- [1] ||
- When the mouse cursor enters a menu, the entry under- |
- neath the mouse cursor is activated; as the mouse |
- moves around the menu, the active entry changes to |
- track the mouse. |
-
- [2] ||
- When button 1 is released over a menu, the active entry |
- (if any) is invoked. |
-
- [3] ||
- A menu can be repositioned on the screen by dragging it |
- with mouse button 2. |
-
- [4] ||
- A number of other bindings are created to support key- |
- board menu traversal. See the manual entry for |
- tk_bindForTraversal for details on these bindings. |
-
- Disabled menu entries are non-responsive: they don't |
- activate and ignore mouse button presses and releases. |
-
- The behavior of menus can be changed by defining new bind- |
- ings for individual widgets or by redefining the class bind- |
- ings.
-
-
-
-
- Tk 9
-
-
-
-
-
-
- menu(n) Tk Commands
-
-
-
- BUGS
- At present it isn't possible to use the option database to |
- specify values for the options to individual entries.
-
-
- KEYWORDS
- menu, widget
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Tk 10
-
-
-
-